10.6 Interoperability for Yubico smart cards

This section contains information about any considerations for using these smart card with other systems.

10.6.1 Unlocking YubiKey tokens

YubiKey tokens include a PIV applet, which means that you can use the MyID Card Utility to carry out a remote challenge/response unlock operation and change the user PIN, and the unlock credential provider to unlock the devices from the Windows logon screen.

See section 2.13, Unlocking smart cards that have a PIV applet.

10.6.2 PIN policy settings

MyID allows you to set various policies for PINs using the settings in the credential profile. MyID enforces these settings for any operations carried out by MyID. For some smart cards, some or all of these settings are applied directly to the card, which means that the settings will also be enforced by third-party tools and utilities.

The following settings are supported for on-card PIN policy settings:

Key:

• Y – Supported.
• blank – Not supported.

MyID also supports the following YubiKey-specific settings by creating a customized card data model file:

• PUK Retries
• Per Container PIN Policy
• Per Container Touch-to-Sign Policy
• Touch OTP

The following settings are supported:

You can configure the on-device settings by editing the card format file; these settings are applied when you issue, reprovision, or update the YubiKey token.

The Yubikey.xml card format file is located on the MyID application server in the following default folder:

C:\Program Files\Intercede\MyID\Components\CardServer\CardFormats\

Important: Do not edit the base Yubikey.xml file, as it may be overwritten by subsequent MyID updates or upgrades – instead, make a copy of the file in the same folder and give it a name that you can use to identify its purpose; for example, if you create a file to change the number of PUK retries to 5, you may want to name the copied file Yubikey_5_PUK_retries.xml.

To select the card format file, in the Credential Profiles workflow, in the Device Profiles section, from the Card Format drop down list select the copy of the Yubikey.xml file you created; for example, Yubikey_5_PUK_retries.xml.

You can configure the YubiKey on-device settings as follows:

• PUK Retries

  In the data model file, set the CardDataModel/PukRetries node to the number of retries.

  The default is 10.

• Per Container PIN Policy

  In the data model file, set the Container/PinPolicy node to one of the following:

  • 01 – the PIN is never needed.
  • 02 – The PIN is needed once per session. (Default, except for Digital Sign Container.)
  • 03 – The PIN is needed for every use. (Default for Digital Sign Container.)

  Important: Do not set the Per Container PIN Policy for the authentication container to 03 (always) – this causes problems when collecting updates. Any signing operation fails if the card is already in an authenticated state, which can occur as a result of authenticating with MyID or Windows. If this occurs, you can collect the updates through the Self-Service App by reinserting the token and retrying the update. However, to prevent this problem from occurring, you are recommended to leave this option at 02 (once) for the authentication container.

• Per Container Touch-to-Sign Policy

  In the data model file, set the Container/TouchPolicy node to one of the following:

  • 01 – never (default)
  • 02 – always
  • 03 – cached

  Note: If you set the Per Container Touch-to-Sign Policy to a value other than 01 (never) there is no on-screen indication when you need to touch the token to proceed; when the token displays a slow steady flashing light, touch the token. If you set this option to always, you must touch the token for each certificate operation; if you set this option to cached, the token caches the authentication for approximately 15 seconds.

• Touch OTP

  You can enable or disable the Touch OTP feature of Yubico devices at issuance (including reprovision) or as a post-issuance device update.

  In the data model file, set the CardDataModel/OTP node to one of the following:

  • <OTP> – if this node is not present, the Touch OTP feature is enabled on issuance or update (according to existing behavior).
  • <OTP>0</OTP> – the Touch OTP feature is disabled on issuance or update.
  • <OTP>1</OTP> – the Touch OTP feature is enabled on issuance or update.

  The Yubikey.xml data model file does not contain the OTP node, which means that the touch OTP feature is enabled by default. An additional card data model, YubikeyNoOTP.xml, is provided that has the Touch OTP feature disabled, with the OTP node set to 0.

Warning: Do not amend any other parts of the card format file. Incorrect configuration may lead to failure to issue a token.

10.6.2.1 Updating existing YubiKey tokens

You can update existing issued YubiKey tokens to use the on-device settings; you can request a card update through MyID, or you can use the Lifecycle API.

When deciding whether to update your existing YubiKey tokens, consider the following:

• If you update the YubiKey token, MyID determines whether any additional certificates need to be added; revoked certificates replaced, and so on; these may require certificates to be added or removed. For any new certificates written to the device, the container that protects the certificate keys will be set to use the Per Container PIN Policy and Per Container Touch-to-Sign Policy as configured in the card format file. No other certificates, and no other on-device policies are affected. The user does not need to set a new PIN for their token.
• If you reprovision the YubiKey token, all content is rewritten to the device, including all certificates, and all on-device settings as configured in the card format file are applied to the device. The user must set a new PIN for their token.

To update an existing YubiKey:

1. Use the Request Card Update workflow to request an update.

   For more details about using this workflow and how it affects your credentials, see the Requesting a card update section in the Operator's Guide.

2. Select one of the following options:

   • Request a resync of the card to the same version of the current profile – select this option if you have made no changes to the credential profile used to issue the token.
   • Request an upgrade of the card to the latest version of the current profile – select this option if you have made changes to the credential profile used to issue the token.

   • Request an upgrade of the card to the latest version of the following profile – select this option if you have created a new credential profile to use for the on-device PIN policy settings.

3. Select the appropriate reason.

   • To carry out a reprovision, replacing all of the certificates on the token, select the There is a problem with the device reason.

   • To carry out an update, which affects only the Per Container PIN Policy or Per Container Touch-to-Sign Policy, and only for certificates that are required to be added because of the update, select the New certificates need to be added to the device reason.

4. Collect the update using the Self-Service App.

For systems with a large user population, you may prefer to create update requests using the Lifecycle API. The relevant section of the submission for generating a card update request is shown below.

For carrying out a full reprovision using the CMSCardRequest schema:

<Card>
 <CardProfile>Yubikey NoOTP</CardProfile>
 <CardRequestedBy>System</CardRequestedBy>
 <OriginalSerialNumber>8115516</OriginalSerialNumber>
 <OriginalDeviceType>YubiKey 4</OriginalDeviceType>
 <StatusMapping>84</StatusMapping>
 <Reprovision>1</Reprovision>
</Card>

For carrying out an update:

<Card>
<CardProfile>Yubikey NoOTP</CardProfile>
<CardRequestedBy>System</CardRequestedBy>
<Update>
 <OriginalSerialNumber>8115516</OriginalSerialNumber>
 <OriginalDeviceType>YubiKey 4</OriginalDeviceType>
 <StatusMapping>86</StatusMapping>
</Update>
</Card>

Replace the values of the nodes in the example above with values corresponding to the user population in your system.

For more information on the Lifecycle API, see the Lifecycle API guide.

10.6.2.2 Using YubiKey tokens for Windows logon

If you want to use your YubiKey tokens for Windows logon, you must set the Per Container Touch-to-Sign Policy to 03 (cached) and Per Contain PIN Policy to 02 (once).

10.6.3 Unlocking

MyID typically sets a randomized personal unlocking key (PUK) when it issues a Yubico smart card. This PUK is not available to any system other than MyID. If you want to unlock a Yubico smart card, you must use MyID (for example, the Self-Service App, MyID Desktop, or the MyID Card Utility).

For information on the MyID Card Utility, see the Remote PIN Management utility for PIV cards section in the Operator's Guide.

10.6.4 PIN attempts

The number of attempts to enter a PIN for a Yubico device is set by the manufacturer, but MyID can override this using the Logon Attempts option on the credential profile.

10.6.5 PIN characters

The SP800-73 PIV specification requires that PIV cards use numeric-only PINs; however, although YubiKey tokens use PIV technology, it is possible to configure MyID to use non-numeric PIN characters for YubiKey tokens. YubiKey tokens support numeric, upper case, lower case, and symbol characters.

10.6.6 PIN length

YubiKey devices have fixed minimum and maximum PIN lengths of 6 and 8 characters respectively. Make sure you set up the credential profile to have a Minimum PIN Length of 6 and a Maximum PIN Length of 8.

10.6.7 Additional identities for YubiKey tokens

The Retired Key Management container slots can be used to store Additional Identity certificates on YubiKey tokens. YubiKey 4 and 5 devices have a total of 20 Retired Key Management containers.

Retired Certificates are written first, followed by AI certs. The combined total of Retired Certificates and Additional Identity certificates must be a maximum of 20 certificates, or the token will run out of available containers.

This functionality requires the YubiKey Smart Card Minidriver installed, which you can obtain from the Yubico website.

For more information on additional identities, see the Additional identities sections in the Administration Guide.

10.6.8 Identification of YubiKey 4 and YubiKey FIPS

YubiKey 4 and YubiKey FIPS devices share an ATR value, and can be differentiated only by their firmware version.

If a YubiKey device has the following ATR:

• 3BF81300008131FE15597562696B657934D4

MyID identifies the device based on the firmware as follows:

• the device has firmware version 4.4.x – YubiKey FIPS.
• the device has any other firmware – YubiKey 4.

10.6.9 Identification of YubiKey 5 and YubiKey SC

YubiKey 5 and YubiKey SC devices share an ATR value, and can be differentiated only by their firmware version.

If a YubiKey device has the following ATR:

• 3BFD1300008131FE158073C021C057597562694B657940

MyID identifies the device based on the firmware as follows:

• the device has a firmware version of 5.3 or greater – YubiKey SC or (if the high bit of the form factor byte of the token's Device Information is set) YubiKey SC FIPS.

• the device has any other firmware – YubiKey 5.

10.6.10 Displaying YubiKey firmware versions

The Identify Card workflow displays the firmware version of your YubiKey devices in the Device Version field.

This value is stored in the MyID database at the point of device personalization from MyID 11.5 onwards – this means that you cannot view the firmware version of YubiKey devices that were issued in previous versions of MyID.

10.6.11 Updating YubiKey devices with incorrect 9B keys

If you are attempting to use MyID Desktop to update a YubiKey device using the Collect My Updates workflow, but the 9B key is incorrect (which may be caused by an issue with earlier versions of the Yubico minidriver, prior to v4.0.4, setting the factory 9B key to a value not known to MyID) you are automatically directed to the Reprovision My Card workflow instead, which recovers your card into a usable state. This process is seamless; note, however, that you must have a role that has access to both the Collect My Updates and Reprovision My Card workflows.

<USBCapabilities>
<!-- 1 = enabled, 0 = disabled -->
  <OTP>0</OTP>
  <U2F>0</U2F>
  <OpenPGP>0</OpenPGP>
  <PIV>1</PIV>    <!-- Note that PIV cannot be disabled or MyID will not be able to manage the token -->
  <OATH>0</OATH>
  <CTAP2>0</CTAP2>
</USBCapabilities>
<NFCCapabilities>
<!-- 1 = enabled, 0 = disabled -->
  <OTP>0</OTP>
  <U2F>0</U2F>
  <OpenPGP>0</OpenPGP>
  <PIV>1</PIV>
  <OATH>0</OATH>
  <CTAP2>0</CTAP2>
</NFCCapabilities>